Creating Custom Behaviors in FrontPage 2003

  • Article

 

Lisa Wollin
Microsoft Corporation

February 2004

Applies to:
     Microsoft® Office FrontPage® 2003

Summary: Learn how Behaviors feature in Microsoft Office FrontPage 2003 allows you to add DHTML scripts quickly and easily to Web pages. FrontPage provides an extensible framework that you can use to create your own custom behaviors. This article explains how you can extend behaviors in FrontPage. (28 printed pages)

Contents

Introduction
Creating a User Interface
Understanding the Behaviors API
Using Your Custom Behavior
Using the FrontPage Object Model
Troubleshooting
Conclusion

Introduction

Dynamic HTML (DHTML) has changed the face of the Internet. Almost every Web page you look at today contains dynamic elements from images that change when you move your mouse over them to pages that can recognize which browser you are using. The Behaviors feature in Microsoft® Office FrontPage® 2003 allows you to insert scripts quickly and easily into your Web pages to help you build dynamic Web pages. You do not need any programming experience, and you do not need to look at a bit of code.

In addition, if you insert scripts into Web pages by using the Behaviors feature, FrontPage manages these scripts. This means that if you delete a script event that isn't referenced elsewhere in a Web page, FrontPage removes the script from the page. On the other hand, if you accidentally remove a script that is referenced in an event somewhere in the page, FrontPage reinserts the script to eliminate script errors. All of this assists non-developers to create dynamic Web pages.

When you install FrontPage, you get approximately 20 predefined Behavior scripts. These scripts include drop-down menus, mouse-over effects, and a client browser check. However, you can do more with the Behaviors feature than simply insert predefined scripts into your Web pages. You can also create your own behaviors, and you can distribute your custom behaviors to others. For example, you may have a script that opens a hyperlink in a pre-sized window; behaviors provides an easy way to make the script available to everyone in your organization. Alternatively, you might want an effective way of distributing scripts to your customers that allows them to insert scripts into their Web pages without working with HTML code, or manage scripts in their Web pages to prevent them from accidentally deleting a script.

Understanding Behavior Components

Extending FrontPage Behaviors is as simple as creating an HTML form component and a script component. The form component contains the user interface for your script. This allows users to insert custom data. You may also use the form page to inform your users of what your script does and allow them to cancel without doing anything. FrontPage displays this page as a Microsoft Windows® dialog box.

The script component contains the scripts that FrontPage inserts into the user's Web page as well as the Behaviors API. The Behaviors API, explained in detail later in this article, is a set of functions that FrontPage uses to process the script. The API contains instructions on which scripts that FrontPage is to insert and provides any additional cleanup tasks that your behavior may need to perform when you delete the script. This file may also contain scripts that the form page needs to function, such as scripts for validating and canceling the form.

While you can put all the code for these two components into a single HTML document, for simplicity, this article discusses these two components as separate files: an HTML form page and a script file. This article walks you through the process of creating these two files to create a custom behavior. The behavior script that you create disables right-click functionality on images in a Web page. Learn the basics of creating the necessary form for the behavior as well as how to work with the Behavior API.

Saving Your Behavior Files

During installation, by default FrontPage installs all built-in behavior files to the default location of drive:\Program Files\Microsoft Office\Templates\1033\Behaviors11\ACTIONS. Although, you can save your custom behavior files to this same folder, we recommend that you save them to the user's Application Data folder located at %userprofile%\Application Data\Microsoft\FrontPage\Behaviors\Actions (where %userprofile% is the file path to the Documents and Settings folder for the current Windows user). Saving your behavior files in either of these locations allows FrontPage to locate them when the application first starts. FrontPage is not able to locate behaviors stored elsewhere. In addition, if you create behaviors that you distribute to others, you should install the files to the user's Application Data folder at the path shown above.

Important   The script that you create in this article is for demonstration purposes only and does not prohibit users from copying images from your Web site. The functionality is limited to prohibiting users from the ability to right-click images and choosing Save Picture As from the context menu and can provide copyright information.

Creating a User Interface

If you look at any of the behaviors installed with FrontPage, you notice that the form that accompanies the behavior resembles a Windows dialog box. Figure1 shows the dialog box for the Go To URL behavior. While the result appears to be a Windows form, the form page for a FrontPage behavior is a simple HTML form page with some added Metadata.

Figure 1. The Go To URL dialog box

The form that you create to accompany your behavior may be very simple to very complex. For example, your behavior script may not require any information from the user; instead, you may want to display a message for your users that allows them to cancel before performing any action. Alternatively, you may have a more complex behavior that requires extensive input from the user, such as controls with which the user provides the information necessary to build a dropdown or expanding menu.

When you create the HTML page, use the TITLE element to specify the text that you want displayed in the title bar of the Windows form. Use the SCRIPT element to specify the name of the corresponding script file that contains both the script and the Behavior API.

Validating and Canceling Your Form

As with most Windows dialog boxes, you should include both an OK button and a Cancel button in your form. You can do this by using the INPUT element with a type attribute value of "button" or the BUTTON element. The Cancel button should have a script in the onclick event that calls the close method of the window object to close the dialog box without doing performing any action.

If your form requires input from the user, your form's onsubmit event should reference a validation script. You should also be aware that you must set the form's onsubmit event to return "false", as shown in the following code, even if your form does not require that the user provide any information. This is necessary to prevent the form from displaying in Microsoft Internet Explorer when the user clicks OK. As with the script for the Cancel button, the validation script closes the dialog box after the fields validate successfully.

<form name="theForm" onsubmit="onValidate(); return false;">

In addition, FrontPage includes several script files that you may want to use. These scripts files are stored in both the default behavior location and the user's Application Data folder mentioned previously, and they contain everything from variables that contain return values for the OK and Cancel buttons to scripts that parse strings and encode URL strings. The scripts for your OK and Cancel buttons should reference the return value variables in the FPLIB.js script file. To reference these variables, add a SCRIPT element that specifies the FPLIB.js file and use the RETURN_OK and RETURN_CANCEL variables to define the form return values.

The following code shows the validation and cancel scripts for the OK and Cancel buttons for the behavior you create later in this article. Notice that if the dialog box does not validate, the script does not apply any return value to the window since the dialog box is not closed. You need to apply the return value only if the script closes the dialog box.

<script type="text/JavaScript" src="FPLIB.JS"></script>

<script>
function onValidate()
{
  var text = document.theForm.Message.value;

  if (text == "")
  {
    alert("You must enter a value for the message.");
    return false;
  }
  else
  {
    window.returnValue = RETURN_OK;
    window.close();
    return true;
  }
}

function onCancel()
{
  window.returnValue = RETURN_CANCEL;
  window.close();
}

</script>

The FPLIB.js script file defines the RETURN_OK and RETURN_CANCEL variables as shown in the following code.

var RETURN_OK  = 1;
var RETURN_CANCEL  = 0;

Although you can manually define these in the validation and cancel scripts in your form page, we encourage you to use the FPLIB.js script file and the above variables. In addition to these variables, you may find the functions contained in the other script files useful. For more information about the functions contained in these files, review any of the following files located at drive:\Program Files\Microsoft Office\Templates\1033\Behaviors11\ACTIONS or at: %userprofile%\Application Data\Microsoft\FrontPage\Behaviors\Actions:

  • _jmpmenu.js
  • _preload.js
  • dom.js
  • fplib.js
  • getobj.js
  • preload.js
  • settext.js
  • strings.js

Important   We strongly discourage you from modifying any of these files or the default behaviors files. Any changes that you make may not be preserved in future FrontPage updates, repairs, or reinstallations. Therefore, if you want to customize any of default behaviors or the accompanying scripts, we recommended that you copy and rename the files before making any changes.

Adding Behavior Metadata

In addition to the HTML used to create the form, you must include one or more of the following metadata to specify dialog box size and to expose the behavior in the list of behaviors that appears in the Behaviors task pane.

Table 1. Behavior metadata

Metadata Description
DialogSize Use the DialogSize metadata to specify the initial size of the behavior dialog box. Use the content attribute to specify the height and width of the dialog box.

Syntax

<meta name="DialogSize" content=" width, height">
DialogResizable Use the DialogResizable metadata to specify whether users can resize the custom behavior dialog box. If omitted, the default is "false".

Syntax

<meta name="DialogResizable" content="true | false">
DHTMLScriptName Use the DHTMLScriptName metadata to specify the name of the script as you want it to appear in the Behaviors task pane.

Syntax

<meta name="DHTMLScriptName" content="script name">

You can also specify a custom submenu that lists one or more scripts. For example, you may want to display your scripts in a drop-down menu with your company name as the name of the menu. To do this, specify the submenu name separated from the Behavior name by a backward slash, as shown in the following code:

<meta name="DHTMLScriptName" content="SubMenu\Behavior">

For example, the default list of behaviors in the Insert menu contains a submenu named "Set Text". In this case, one of the menu items contains the following metadata:

<meta name="DHTMLScriptName" content="Set Text\Set Text of &Layer">

The following code taken from the GoToUrl.htm file (located in the default folder) demonstrates the use of these META elements.

<meta name="DHTMLScriptName" content="Go To &URL">
<meta name="DialogResizable" content="true">
<meta name="DialogSize" content="475,100">

Note   The ampersand (&) in the preceding example does not actually do anything. You can use it or leave it out without affecting either the function or display of your behavior.

Creating the Disable Right Click Behavior Form File

As mentioned earlier, this article shows you how to create a very simple behavior. The behavior disables the right-click capabilities when someone right-clicks on an image displayed in a Web page. (Please see the security note earlier in this article.) The form for the Disable Right-Click behavior contains a TEXTAREA element into which you type the message that you want displayed when someone right-clicks on an image, as well as OK and Cancel buttons that allow you to invoke or cancel the action. In addition, to separate the scripts that FrontPage uses to validate and cancel the form from the scripts included in the Behavior API, the form scripts are contained in the form page rather than in the script document. However, you can easily put all scripts in the same document.

To create the form page for the Disable Right Click behavior

  1. Start FrontPage.

  2. Create a Web page.

  3. Switch to Code view.

  4. Select the code that is displayed (press Ctrl-A) and paste the following HTML code. Notice that this code contains all three META elements. Also, notice that this code contains a STYLE element. This provides formatting for the form buttons and the tables. As with other Web pages, you can use a global STYLE element or specify styles inline by using the style attribute. Finally, notice that the first SCRIPT element contains a reference to disablerightclick.js. This file contains the Behaviors API functions that you create later in this article.

    <html>
<head>

<meta name="DHTMLScriptName" content="Disable Right Click on Image">
<meta name="DialogResizable" content="false">
<meta name="DialogSize" content="425,125">

<title>Disable Right Click on Image</title>

<script type="text/JavaScript" src="DISABLERIGHTCLICK.JS"></script>
<script type="text/JavaScript" src="FPLIB.JS"></script>

<script language="javascript" >
function onValidate()
{
   var text = document.theForm.Message.value;

    if (text == "")
    {
        alert("You must enter a value for the message.");
        return false;
    }
    if (text.indexOf("'") > 0)
    {
        alert("You cannot use single quotes within your message.\n" +
            "Please try again.");
        return false
    }   else
    {
        window.returnValue = RETURN_OK;
        window.close();
        return true;
    }
}

function onCancel()
{
    window.returnValue = RETURN_CANCEL;
    window.close();
}

</script>

<style> 
    button    { width: 8em }
    table     { border: none; border-collapse: collapse }
</style>

</head>

<body>

<form name="theForm" onsubmit="onValidate(); return false;">
    <table width="100%">
    <tr>
            <td width="100%">
            <p>This action inserts a script that disables 
               the right click functionality for the selected image. 
               Type the message that you want displayed when the user 
               right-clicks on the image. This message may be a
               copyright notice or an explanation that the user doesn't 
               have the right to copy the image.</p>
             <p>IMPORTANT: This behavior is presented merely as a an 
               example of customizing behaviors. Using it does not 
               prohibit users from copying images from your Web site by
               using other easily accessible browser tools. At most, it
               prohibits users from right clicking on images and
               choosing <b>Save Picture As</b> from the context menu
               and can provide a copyright notice or explanation that
               copying of the images is not authorized.</p>
            </td>
        </tr>
        <tr>
            <td width="100%"><hr><textarea name="Message" rows="4" 
               cols="100%"></textarea></td>
        </tr>
        <tr>
            <td>
            <table width="100%">
                <tr>
                    <td width="100%"></td>
                    <td>
                    <table width="100%">
                        <tr>
                            <td>
                                <button tabindex="1" name="Ok" 
                                  id="btnOk" type="submit">OK</button>
                            </td>
                            <td>&nbsp;</td>
                            <td>
                                <button tabindex="2" name="Cancel" 
                                 id="btnCancel"
                                  onClick="onCancel();">Cancel</button>
                            </td>
                        </tr>
                    </table>
                    </td>
                </tr>
            </table>
            </td>
        </tr>
    </table>
</form>

</body>
</html>

  5. Save the page as "DisableRightClick.htm" to %userprofile%\Application Data\Microsoft\FrontPage\Behaviors\Actions.

    Note   At this point, you cannot select this behavior from the list of behaviors in the Behaviors task pane. FrontPage needs the Behavior API contained in the script file before it displays the Behavior name in the list of behaviors.

Understanding the Behaviors API

The script file contains the script or scripts that are necessary for the behavior to function in the Web page as well as the Behaviors API functions that FrontPage uses with the behaviors. There are five functions in the Behaviors API. The following sections describe these functions in detail.

Note   All the functions in the Behaviors API are required when creating your custom behaviors except the initPropertyDialog and removeScript functions.

getScript function

The getScript function returns a string that represents the name of one or more script functions that FrontPage inserts into the active document. You can also specify the actual script in the returned string. FrontPage then inserts the function specified in the returned string into a SCRIPT element in the active document.

Separate multiple function names with a comma. If you specify more than one script name, the first script name specified must match the script returned by the getScriptCall function. For example, the following return statement returns three script names: Script1, Script2, and Script3.

return "Script1, Script2, Script3"

Signature

function getScript()

Example

The following example shows the getScript function for the Disable Right Click behavior. The return value for the getScript function is the string "DisableRightClick", which is the name of the function that is specified for the Disable Right Click behavior.

function getScript()
{
    return "DisableRightClick";
}

Note   In most cases, you define the behavior script elsewhere in the behavior script file and you return only the function name. FrontPage then copies the entire function into the Web page. However, you can return the entire script. For example, in the following code, the getScript function returns a shortened version of the DisableRightClick function.

function getScript()
{
    var sScript = "function DisableRightClick(copyright)" +
        "{alert(copyright);}";

    return sScript;
}

getScriptCall function

The getScriptCall function returns the script code that FrontPage inserts into the target event handler that you specify in the isScriptEnabled function. This function returns the DHTML script that you specify in the getScript function. You can populate the function call with the values from the HTML form fields. For example, if your behavior form allows the user to type text into a field, you may wish to use the corresponding string value in the returned script.

If you specify multiple scripts in the getScript function, you need to use the getScriptCall function to insert the events and script calls into the Web page. To do this, use the FrontPage VBA Page object model. For more information on the members added to the FrontPage object model that support behaviors, see Using the FrontPage Object Model later in this article.

Signature

function getScriptCall()

Example

The following example shows the getScriptCall function for the Disable Right Click behavior. The return value is the value that FrontPage adds to the event handler for the element. In this case, the script uses the document object to access the value of a form field.

function getScriptCall()
{
    var message = document.theForm.Message.value;
    return "DisableRightClick('" + message + "');";
}

isScriptEnabled function

The isScriptEnabled function returns a Boolean that specifies whether a behavior is available within the context of the target document. For example, if your script is only useful for a specific element in a page, you can verify whether the element that receives the corresponding behavior matches that element. If the returned value is false, the script is not available and is unavailable in the list of scripts on the Behaviors task pane. All other values indicate that the script is available.

Values other than false include true or a string that specifies the name of the event that you want to receive the script. For example, if you want the onclick event for an element to receive the script, you return the string value onclick for the isScriptEnabled function.

If you do not specify an event name in the return value, the event specified is the default event for the element. For example, if the Behavior element is the BODY element, the onload event is automatically populated with the event script; however, if you want the onmouseover event to receive the event script, you need to return the value onmouseover for the isScriptEnabled function.

Signature

function isScriptEnabled()

Example

The following example is the isScriptEnabled function for the Disable Right Click behavior. This script indicates that the behavior is enabled and available from the list in the Behaviors task pane if the Behavior element, the element that receives the Behavior script, is an IMG element. If this is the case, the isScriptEnabled function returns a string value of "onmousedown", which indicates that the event handler that receives the script is the onmousedown event. In all other cases, the function returns false, which causes FrontPage to disable the item in the list of behaviors.

function isScriptEnabled()
{
    if (FrontPage.ActiveDocument.behaviorElement.tagName == "img")
    {
        return "onmousedown";
    }
    else
    {
        return false;
    }
}

initPropertyDialog function

The initPropertyDialog function initializes the form controls. This allows you to populate the form with values from a previously attached behavior. For example, if you have a behavior that inserts a drop-down menu and a user previously inserted a drop-down menu by using your behavior, you may want to populate the dialog box with the menu values prior to displaying the dialog box.

If your behavior does not have input fields on the form page, then you can omit the initPropertyDialog function.

Signature

function initProperty(strScriptCall)

Parameters

strScriptCall   Returns a string that matches the return value of a previous call to the getScriptCall function.

Example

The following example shows the initPropertyDialog function for the Disable Right Click behavior. This function allows the message that a user inserted previously for the Disable Right Click behavior to display in the Disable Right Click dialog box. The strScriptCall parameter provides the value of the onmousedown event handler that the behavior previously inserted. In this case, the value of the strScriptCall parameter is "DisableRightClick('message')", italics indicate the value of the message that the user entered. Therefore, in order to get the message, the script needs to remove the surrounding text. This script assumes that there is a string with an opening single quote and a closing single quote and no nested single quotes.

function initPropertyDialog(strScriptCall)
{
    var sMessage = strScriptCall;
    var iStart = sMessage.indexOf("'") + 1;
    var iStop = sMessage.indexOf("'", iStart);

    sMessage = sMessage.substring(iStart, iStop)
    document.theForm.Message.value=sMessage;
}

removeScript function

The removeScript function performs any additional clean up that is necessary to remove the scripts that are part of this behavior. FrontPage automatically removes the script call that the getScriptCall function returns, as well as any unused copies of the script that the getScript function returns. However, if your behavior adds any supporting scripts or event handlers to a Web page, you need to use the removeScript function to remove the scripts or event handlers. FrontPage performs the automatic clean up even if you define code for the removeScript function.

For example, if your behavior inserts a script call for the onmouseover event and then manually inserts a script call for the onmouseout event within the getScriptCall function, you need to remove the script for the onmouseout event in the removeScript function. FrontPage automatically removes the script for the onmouseover event.

Signature

function removeScript(oDoc, strScriptCall)

Parameters

oDoc   Returns a document object that represents the active document in FrontPage.

strScriptCall   Returns a string that matches the return value of a previous call to the getScriptCall function.

Example

The following example shows removing an event for the onmouseout event.

function removeScript(oDoc, strScriptCall)
{
    var oElement = oDoc.behaviorElement;
    oDoc.removeScript(oElement, "onmouseout")
}

Creating the Disable Right Click Behavior Script File

Now you are ready to create the Behavior API script file for the Disable Right Click custom behavior. The following steps describe how to do this.

  1. Start FrontPage.

  2. Create a new Web page.

  3. Switch to Code view.

  4. Select the code that is displayed (press Ctrl-A) and paste the following HTML code. Most of the code below was included in the API function descriptions above.

Note You may need to copy the following code into Notepad or another text editor before pasting it into FrontPage.

    //////////////////////////////////////////////////////////////////////////
    // BEHAVIOR FUNCTIONS
    // This is the code that is unique for this behavior.
    // This code allows your custom behavior to function and may contain.
    // one or more custom scripts that FrontPage inserts into Web pages
    // when the someone uses your behavior.
    //////////////////////////////////////////////////////////////////////////
    
    function DisableRightClick(copyright)
    {
        if (navigator.appName == "Netscape Navigator" || "Mozilla" &&
            window.event.which == 2 || window.event.which == 3)
        {
            alert(copyright);
        }
        else if (navigator.appName == "Microsoft Internet Explorer" && 
            window.event.button == 2 || window.event.button == 3)
        {
            alert(copyright);
        }
    }
    
    
    //////////////////////////////////////////////////////////////////////////
    // GETSCRIPT FUNCTION – Required Behaviors API function
    //////////////////////////////////////////////////////////////////////////
    
    function getScript()
    {
        return "DisableRightClick";
    }
    
    
    //////////////////////////////////////////////////////////////////////////
    // GETSCRIPTCALL FUNCTION – Required Behaviors API function
    //////////////////////////////////////////////////////////////////////////
    
    function getScriptCall()
    {
        var sMessage = document.theForm.Message.value;
    
       return "DisableRightClick('" + sMessage + "');";
    }
    
    
    //////////////////////////////////////////////////////////////////////////
    // ISSCRIPTENABLED FUNCTION – Required Behaviors API function
    //////////////////////////////////////////////////////////////////////////
    
    function isScriptEnabled()
    {
        if (FrontPage.ActiveDocument.behaviorElement.tagName == "img")
        {
            return "onmousedown";
        }
        else
        {
        return false;
        }
    }
    
    
    //////////////////////////////////////////////////////////////////////////
    // INITPROPERTYDIALOG FUNCTION – Required Behaviors API function
    //////////////////////////////////////////////////////////////////////////
    
    function initPropertyDialog(strScriptCall)
    {
        var sMessage = strScriptCall;
        var iStart = sMessage.indexOf("'") + 1;
        var iStop = sMessage.indexOf("'", iStart);
        
        sMessage = sMessage.substring(iStart, iStop)
        document.theForm.Message.value=sMessage;
    }
    //////////////////////////////////////////////////////////////////////////
    // INITPROPERTYDIALOG FUNCTION – Optional Behaviors API function
    //////////////////////////////////////////////////////////////////////////
    function initPropertyDialog(strScriptCall)
    {
        var sMessage = strScriptCall;
        var iStart = sMessage.indexOf("'") + 1;
        var iStop = sMessage.indexOf("'", iStart);
        
        sMessage = sMessage.substring(iStart, iStop)
    
        document.theForm.Message.value=sMessage;
    }
    //////////////////////////////////////////////////////////////////////////
    // REMOVESCRIPT FUNCTION – Optional Behaviors API function
    //////////////////////////////////////////////////////////////////////////
    // Not Apllicable

  1. Save the page as "DisableRightClick.js" to %userprofile%\Application Data\Microsoft\FrontPage\Behaviors\Actions.

    Note   Notice that both of the files for the Disable Right Click behavior have the same filename, "DisableRightClick", with different file extensions. If you look in the default behavior folder (C:\Program Files\Microsoft Office\Templates\1033\Behaviors11\ACTIONS), you see that this is also true for the behaviors that ship with FrontPage. While it is not necessary to name your behavior files in this manner, we strongly recommend doing so, because it makes maintaining the behavior files easier. If you give your form page and script file different names, you must also make sure to add a reference the correct script file in the SCRIPT element located in the custom behavior's HTML form page.

Using Your Custom Behavior

Once you create both files and save them to your Application Data folder, you must restart FrontPage. FrontPage loads behaviors upon startup, so you do not see the Disable Right Click behavior in the list of available behaviors until you restart the application.

After you restart, use the following steps to see the Disable Right Click behavior in action.

To view the Disable Right Click behavior in action

  1. Create a new page.

  2. Insert an image into the page.

  3. Select the image.

  4. Press CTRL-F1 to display the task pane if it does not automatically appear.

  5. Select the Behaviors task pane from the list of available task panes.

  6. Click Insert to see a list of available behaviors. If the behavior name appears in gray text, the behavior is not available. This is because the Disable Right Click behavior is available only if the user selects an image. Therefore, your result may be one of the following images.

    Figure 2. Behavior when image is selected

    Figure 3. Behavior when image is not selected

If you are unable to see your new custom behavior in the list of behaviors, you may need to do some additional troubleshooting. For troubleshooting assistance, see Troubleshooting later in this article.

Using the FrontPage Object Model

In order to make scripting custom behaviors possible, FrontPage allows you to script against the FrontPage object model. Therefore, the FrontPage object model has several new members that are designed specifically for working with behaviors. While these are included in the FrontPage VBA object model and you can use them in macros and add-ins, they are most useful when scripting behaviors as they allow you to access and modify the a page as well as access dialog boxes within FrontPage that provide formatting information.

To access the FrontPage object model from a script, use the FrontPage accessor property. For example, the code FrontPage.ActiveDocument accesses the Web page currently displayed in FrontPage. This method is very similar to how you do this when writing code for macros or add-ins. For more information about working with the FrontPage object model, see the FrontPage VBA online help, included with FrontPage, and the FrontPage 2002 Software Development Kit

Important   You can access the following methods and property only from within the Behavior API or from a FrontPage add-in or macro. You cannot use them in DHTML scripts that you include a reference to in Web pages that display in a browser.

You should also note that although the names of some of the methods are the same as functions in the Behaviors API, such as the getScript function in the Behaviors API and the getScript method in the FrontPage object model, they do not perform the same tasks. The Behaviors API is a separate development platform upon which you can build custom behaviors. The following methods and property are part of the FrontPage object model.

addScript method

Use the addScript method to add a script to an element for a specified event.

Signature

FrontPage.ActiveDocument.addScript(element, event, script, index)

Parameters

element   Required. Specifies the element that receives the action.

event   Required. Specifies the name of the event that causes the script to run.

script   Required. Specifies the script that runs when the event occurs.

index   Optional. Specifies where to insert the script if an event contains more than one script. If omitted, inserts the script at the end of the list of scripts.

Example

The following example adds an onmouseout event to the Behavior element.

function SampleAddScript()
{
    var ele = FrontPage.ActiveDocument.behaviorElement;
    FrontPage.ActiveDocument.AddScript(ele, "onmouseout", "RestoreImage");
}

behaviorElement property

Use the behaviorElement property to return an IHTMLElement object that represents the top-most parent element of the current selection. This element corresponds to the value of the Scripts on Tag option in the Behaviors task pane.

Signature

FrontPage.ActiveDocument.behaviorElement

Example

The following example adds an onmouseout event to the Behavior element.

function SampleAddScript()
{
    var oEle = FrontPage.ActiveDocument.behaviorElement;
    FrontPage.ActiveDocument.AddScript(oEle, "onmouseout",
    "RestoreImage");
}

getScript method

Use the getScript method to return a String that represents the script for a specific event for an element. The parameters for the getScript method allow you to specify the element and the event for which to return the script.

Signature

FrontPage.ActiveDocument.getScript(element, event, index)

Parameters

element**   **Required. Specifies the element that contains the script.

event**   **Required. Specifies the name of the event that causes the script to run.

index**   **Required. Specifies the script item if an event specifies more than one script to run when the event occurs. Multiple scripts are one-based rather than zero-based so that the index for the first script (in the case of multiple scripts) or the only script (in the case of a single script) for an event is "1".

Example

The following example captures the script for a specified event.

function GetOnClickScript()
{
 var oEle = FrontPage.ActiveDocument.behaviorElement;
 var sScript = FrontPage.ActiveDocument.getScript(oEle, "onclick", 1);
}

reapplyScript method

Use the reapplyScript method to verify that the functions associated with script calls defined for one or more elements are within a SCRIPT element in the HEAD element of a document. You can specify the element to check by using the element parameter. If you omit the optional element parameter, FrontPage checks all elements within a page. If the referenced scripts are missing, FrontPage reinserts the scripts.

Signature

expression.reapplyScript(element)

Parameters

*Element   *Optional. Specifies an element within the document. If omitted, the reapplyScript method checks all elements within the document.

Remarks

The reapplyScript method is most useful in add-ins that extend behaviors. The method allows you to reinsert scripts that a user may have inadvertently deleted, thus eliminating errors that may result.

Example

The following example reinserts any deleted scripts to reduce script errors.

function ReapplyAllScripts()
{
    FrontPage.ActiveDocument.reapplyScript();
}

removeScript method

Use the removeScript method to remove the script call in a specified event within an element. The parameters for the removeScript method allow you to specify the element and the event for which to remove a script.

Signature

expression.removeScript(element, event, index)

Parameters

Element**   **Required. Specifies the element that contains the script.

event**   **Required. Specifies the name of the event handler that causes the script to run.

index**   **Optional. Specifies the script item if an event specifies more than one script to run when the event occurs. Multiple scripts are one-based rather than zero-based so that the index for the first script for an event is "1". If omitted, removes all scripts from the specified event handler.

Remarks

You use the removeScript method within the RemoveScript function in the Behaviors API to clean up any scripts that you added by using the adscript method.

Example

The following example removes all scripts from the onclick event handler.

function RemoveCustomScript()
{
    var objBody = FrontPage.ActiveDocument.behaviorElement
    FrontPage.ActiveDocument.removeScript(objBody, "onclick")
}

ShowBordersShadingDialog method

The ShowBordersShadingDialog method displays the Borders and Shading dialog box and returns a String that represents the Cascading Style Sheet (CSS) property settings for the borders and shading properties selected in the Borders and Shading dialog box. A value is returned when the users clicks OK. If the user clicks Cancel, the method returns an empty String.

Signature

FrontPage.ShowBordersShadingDialog(strCSSIn)

Parameters

*strCSSIn*****Optional. A String that represents the initial settings for the dialog box.

Example

The following example displays the Borders and Shading dialog box, and then sets the border style for the Behavior element to the border settings returned.

function ShowBorderDialog()
{
    var strCSSIn = "border: 3 double #00FFFF";
    var strCSSOut = FrontPage.ShowBordersShadingDialog(strCSSIn);

    if (strCSSOut != "")
    {
        FrontPage.ActiveDocument.behaviorElement.Style.Border = strCSSOut;
    }
}

ShowFontDialog method

The ShowFontDialog method displays the Font dialog box and returns a String that represents the CSS properties for the font selected in the Font dialog box. A value is returned when the users clicks OK. If the user clicks Cancel, the method returns an empty String.

Signature

expression.ShowFontDialog(strCSSIn)

Parameters

*strCSSIn*****Optional. A String that represents the initial settings for the dialog box.

Example

The following example displays the Font dialog box, and then returns the resulting CSS.

function ShowFontDialogBox()
{
    var strCSSIn = "font-family: 'Verdana'; font-size : 12pt; " +
        "color: red; font-weight: bold;"
    var strCSSOut = FrontPage.ShowFontDialog(strCSSIn);

    return strCSSOut;
}

ShowHTMLDialog method

Use the ShowHTMLDialog method to display a custom dialog box by using the contents of an HTML page, for example, when your custom behavior contains additional pages that you need to display from your main behavior form page.

Signature

FrontPage.ShowHTMLDialog(Url, pVarArgIn)

Parameters

Url**   **Required. The path and file name of the page to render as a dialog box. If the HTML page is located in the same folder as the file that contains the script call, the path is not required.

pVarArgIn**   **Optional. Data used to set the initial settings of the custom dialog box.

Example

The following example displays an HTML page as a Windows dialog box.

function ShowHTMLDialogBox()
{
    FrontPage.ShowHTMLDialog("test.htm");
}

ShowHyperlinkParameters method

The ShowHyperlinkParameters method displays the Hyperlink Parameter dialog box and returns a String that represents the hyperlink and the hyperlink parameters, separated by a question mark. For more information on the specific parameters that this method can use or return, see the FrontPage VBA online help.

Signature

FrontPage.ShowHyperlinkParameters(bstrPath, bstrQuery, bstrColumns, bstrColTypes)

Parameters

bstrPath**   **Required. Specifies the Web address for the hyperlink.

bstrQuery*   ***Required. Specifies the query string to pass in when opening the linked page.

bstrColumns**   **Required. Specifies a comma-delimited String that contains the names of the database columns that are available for use in the URL.

*bstrColTypes ***   **Required. Specifies a comma-delimited String that represents the data type values of the database columns.

Example

The following example displays the Hyperlink Parameters dialog box with the specified URL and settings.

function ShowHyperlinkParametersDialogBox()
{
    FrontPage.ShowHyperlinkParameters("http://www.cohowinery.com/wines.asp",
        "type=red", "CategoryID,CategoryName,Description", "3,202,202");
}

ShowPickURLDialog method

The ShowPickURLDialog method displays the Edit Hyperlink dialog box and returns a String that represents the URL for the file that the user has selected in the Edit Hyperlink dialog box.

Signature

FrontPage.ShowPickURLDialog(strBaseURL, strFileURL)

Parameters

*strBaseURL    *Optional. The base URL for the resulting hyperlink.

strFileURL**   **Optional. The selected page for a new hyperlink. The user may change this by selecting a different page in the Edit Hyperlink dialog box.

Example

The following function displays the Edit Hyperlink dialog box populated with the specified Web site and page.

function ShowPickURLDialogBox()
{
    var strURLBase = FrontPage.ActiveWeb.Url;
    var strURLFile = "wines.htm";
    var strURLOut = FrontPage.ShowPickURLDialog(strURLBase, strURLFile);
}

ShowPositionDialog method

The ShowPositionDialog method displays the Position dialog box and returns a String that represents the CSS properties for the position of an element.

Signature

FrontPage.ShowPositionDialog(strCSSIn)

Parameters

strCSSIn**   **Optional. A String that represents the initial custom settings for the dialog box.

Example

The following example displays the Position dialog box pre-populated with the specified position properties.

function ShowPositionDialogBox()
{
    var strCSSIn = "position: absolute; left: 750";
    var strCSSOut = FrontPage.ShowPositionDialog(strCSSIn);

    if (strCSSOut != "")
    {
        FrontPage.ActiveDocument.behaviorElement.setAttribute ("style", strCSSIn);
    }
}

Troubleshooting

As you create your custom behaviors, you may have issues arise that either make the behavior unavailable or do not function as you intended. The following list provides troubleshooting help on the most common debugging issues.

My behavior doesn't appear in the Insert menu in the Behaviors task pane

There may be several reasons why your behavior does not appear:

  • Every time you change the code, you must restart FrontPage before the changes appear. If you have recently updated the code and have not restarted FrontPage, try restarting.
  • If there are any code errors, rather than displaying error messages, FrontPage ignores the behavior. Therefore, make sure that your code is completely accurate. Also, adhere to strict coding rules when writing your script code. Make sure that you have not omitted a closing semicolon or forgotten a closing parenthesis.
  • Have you inserted a line for the return value in the OK and Cancel buttons? These are required and may cause your code to raise an error in FrontPage.
  • Have you referenced the correct document? If you are accessing fields in your form page, you can access the document object directly. However, if you are coding against the active page in FrontPage (for example, verifying that the behavior element is of a certain type), you must reference it through the FrontPage object model.
  • Make sure your custom behavior specifies a unique name in the DHTMLScriptName metadata. If the name matches the name of an existing behavior, the same name appears twice on the Insert menu in the Behaviors task pane.

When I click OK, my form page opens in a browser window

When you specify the onsubmit event for your behavior form, you must specify a return value of false even if you specify a validation function. The following example shows an opening FORM element with the onsubmit event correctly coded.

<form name="theForm" onsubmit="onValidate(); return false;">

When I click OK, my form page closes but nothing happens

Before you close the behavior form, you must specify a value for the returnValue property. This value indicates whether the user clicked the OK button or the Cancel button. The best way to do this is to use the FPLIB.js script file that contains return value variables that you can use.

The following example shows the code for a successful validation when the user clicks the OK button.

window.returnValue = RETURN_OK;
window.close();
return true;

The following example shows the code for when the user clicks the Cancel button.

window.returnValue = RETURN_CANCEL;
window.close();

The RETURN_OK and RETURN_CANCEL variables are defined in the FPLIB.js file. To use these variables, you need to add a reference to the script file. For more information, see the section Validating and Canceling Your Form.

My behavior appears grayed-out in the Insert menu

The main reason why your behavior may be displayed in gray text (making it unavailable) in the Insert menu is because of the location of your cursor. For example, the Disable Right Click behavior shown in this article requires that you have an image selected or that the cursor is located within an IMG element. If this is not the case, FrontPage displays the behavior name in gray text.

If your behavior still does not display correctly, verify that the isScriptEnabled function in the Behaviors API script file does not specify a complex condition that cannot be met. For example, a condition that says that the behavior is available only when the user places the cursor inside of a P element with an id attribute value of "firstpara" disable the script for all other P elements.

Another reason your behavior may appear in gray text is that the compatibility settings for the targeted browser are set to a browser that does not support the behavior's functionality that the behavior adds. For example, Internet Explorer 3.0 and Netscape Navigator 3.0 and earlier versions do not support all scripting. Use the following steps to change browser compatibility

  1. Click on Tools, and then Page Options.
  2. Select Authoring.
  3. Change the Schema version to Internet Explorer 4.0/Navigator 4.0 or Internet Explorer 5.0.

Conclusion

The use of Dynamic HTML has grown over the past five years, and Web developers will likely continue to use it extensively. The Behaviors feature in Microsoft Office FrontPage 2003 helps you to insert Dynamic HTML scripts into your Web pages quickly and manages these scripts to reduce script errors. Now that you know how to create your own custom behaviors, the possibilities for extending behaviors are endless.